C/C++ Users Group Library 1996 July

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 403_01 / matrix.doc < prev next >

Wrap

Text File | 1993-09-22 | 17.9 KB | 482 lines

/* *----------------------------------------------------------------------------- * file: matrix.doc * desc: document for matrix toolbox function calls * by: ko shu pui, patrick * date: 24 may 92 v0.4 * 23 sep 93 v0.41 *----------------------------------------------------------------------------- */ =============================================================================== 0. INTRODUCTION =============================================================================== This document only provides you the following information: 0.1 How to create and free a matrix 0.2 Description of each matrix function call 0.3 Some hints to use this toolbox Remember that this document will NOT describe the data structure and any technical details of the toolbox - just because this document is aimed at to be a sort-of "User's Guide" for programmers. =============================================================================== 1. OUR MATRIX OF REFERENCE =============================================================================== In order to avoid terms confusion, here is our matrix of reference (matrix A) which is of size m x n. Column Row 0 1 2 n-1 0 [ a0,0 a0,1 a0,2 ... a0,n-1 ] A = 1 [ a1,0 a1,1 a1,2 ... a1,n-1 ] 2 [ a2,0 a2,1 a2,2 ... a2,n-1 ] [ ... ... ... ... ... ] m-1 [ am-1,0 am-1,1 am-1,2 ... am-1,n-1 ] =============================================================================== 2. BASIC MATRIX OBJECT OPERATION =============================================================================== ------------------------------------------------------------------------------- Function : MATRIX mat_creat (int m, int n, int type) Synopsis : creation of a matrix which can be used by the matrix toolbox functions; memory is allocated for this object; and some initialization is performed. Parameter: m: number of rows n: number of columns type: matrix initialization type where type= UNDEFINED do not initialize the matrix ZERO_MATRIX fill zero to all matrix elements UNIT_MATRIX fill a one to all matrix element ai,j where i=j Return Value: the matrix object Example: MATRIX A; /* * create a 15 x 15 matrix; * do not initialize the elements */ A = mat_creat( 15, 15, UNDEFINED); /* * put a 4 in element A(0,14) of matrix A, * put a 2 in element A(3,5) of matrix A */ A[0][14] = 4.0; A[3][5] = 2.0; See Also: mat_free(), for Accessing a matrix, see this example. ------------------------------------------------------------------------------- Function: MATRIX mat_fill ( MATRIX A, int type ) Synopsis: initialize a matrix will a simple type Parameter: A: the matrix object for which mat_creat() has been called type: matrix initialization type where type= UNDEFINED do not initialize the matrix ZERO_MATRIX fill zero to all matrix elements UNIT_MATRIX fill a one to all matrix element ai,j where i=j Return Value: MATRIX A Example: MATRIX A; ... /* * fill the matrix A will zeroes */ mat_fill( A, ZERO_MATRIX ); See Also: mat_creat() ------------------------------------------------------------------------------- Function : int mat_free ( MATRIX A ) Synopsis : free all memory occupied by the matrix object A Parameter: A: the matrix object for which mat_creat() was called Return Value: None Example: MATRIX A; A = mat_creat(...); ... mat_free(A); Note: since memory may be a very scarce resource in a computer, as a C programmer you are advised to free up the matrix as soon as that matrix will not be used any more in future. See Also: mat_creat() ------------------------------------------------------------------------------- Function: MatCol ( A ) Synopsis: find out the number of columns of a matrix object A Parameter: A: the matrix object for which mat_creat() was called Return Value: number of columns Example: int i; ... i = MatCol(A); Note: this is a macro See Also: MatRow() ------------------------------------------------------------------------------- Function: MatRow ( A ) Synopsis: find out the number of rows of a matrix object A Parameter: A: the matrix object for which mat_creat() was called Return Value: number of rows Example: int i; ... i = MatRow(A); Note: this is a macro See Also: MatCol() ------------------------------------------------------------------------------- Function: MATRIX mat_colcopy1 ( MATRIX A, MATRIX B, int j1, int j2 ) Synopsis: copy a column from a matrix A to a column at matrix B Parameter: A, B: the matrix objects for which mat_creat() was called column j1 of A is copied to column j2 of B; Return Value: MATRIX A Example: MATRIX A, B; A = mat_creat( 5, 4, ZERO_MATRIX ); B = mat_creat( 5, 4, UNDEFINED ); /* * copy column 2 of A to column 0 of B */ mat_colcopy1( A, 2, B, 0 ); Note: the sizes of rows of A, B must be the same See Also: mat_copy() ------------------------------------------------------------------------------- Function: MATRIX mat_copy ( MATRIX A ) Synopsis: duplicate a matrix Parameter: A: the matrix object for which mat_creat() was called Return Value: Another allocated matrix object whose contents are same as A Example: MATRIX A, B; A = mat_creat( 5, 4, ZERO_MATRIX ); /* * B is also a 5 x 4 zero matrix now */ B = mat_copy( A ); ... mat_free( B ); See Also: mat_colcopy1() ------------------------------------------------------------------------------- =============================================================================== 3. BASIC MATRIX OBJECT INPUT/OUTPUT OPERATION =============================================================================== ------------------------------------------------------------------------------- Function: int fgetmat (MATRIX A, FILE * fp) Synopsis: read a matrix from stream Parameter: A: allocated matrix fp: a stream pointer obtained from fopen() or predefined pointer in standard library such as stdin Return Value: number of matrix elements read Example: MATRIX A; FILE *fp; A = mat_creat(3, 3, UNDEFINED); fp = fopen("mymatrix.dat", "r"); fgetmat( A, fp ); See Also: mat_dumpf(), mat_dump(), mat_fdump(), mat_fdumpf() ------------------------------------------------------------------------------- Function: MATRIX mat_dump (MATRIX A) MATRIX mat_dumpf (MATRIX A, char * format) MATRIX mat_fdump (MATRIX A, FILE * fp) MATRIX mat_fdumpf (MATRIX A, char * format, FILE * fp) Synopsis: mat_dump: dump a matrix to std output with default format mat_dumpf: dump a matrix to std output with specified format mat_fdump: dump a matrix to a file with default format mat_fdumpf:dump a matrix to a file with specified format Parameter: A: allocated matrix format: same as printf() 's format parameter, but can only be floating point type, such as "%.2f ", etc. fp: file pointer obtained via fopen() Return Value: matrix A Example: MATRIX A; A = mat_creat( ... ); ... /* * dump the matrix to standard output and each element * is restricted to 2 precision format */ mat_dumpf( A, "%.2f "); See Also: fgetmat() ------------------------------------------------------------------------------- =============================================================================== 4. BASIC MATRIX OBJECT MATHEMATICAL OPERATION =============================================================================== ------------------------------------------------------------------------------- Function: MATRIX mat_add (MATRIX A, MATRIX B); MATRIX mat_sub (MATRIX A, MATRIX B); Synopsis: mat_add: addition of 2 matrices mat_sub: substraction of 2 matrices Parameter: A, B: allocated matrices Return Value: a newly allocated matrix which is the result of the operation Example: MATRIX A, B, C; A = mat_creat( 5, 5, UNIT_MATRIX ); B = mat_creat( 5, 5, UNIT_MATRIX ); C = mat_add( A, B ); mat_dump( C ); mat_free( A ); mat_free( B ); mat_free( C ); Note: A, B must be of the same dimensions See Also: mat_mul, mat_inv ------------------------------------------------------------------------------- Function: MATRIX mat_mul (MATRIX A, MATRIX B); Synopsis: multiplication of 2 matrices Parameter: A, B: allocated matrix Return Value: a newly allocated matrix which is the result of the operation Example: MATRIX A, B, C; A = mat_creat( 5, 3, UNIT_MATRIX ); B = mat_creat( 3, 6, UNIT_MATRIX ); /* * C is now a 5 x 6 matrix */ C = mat_add( A, B ); mat_dump( C ); ... Note: the column dimension of A must equal row dimension of B See Also: mat_add, mat_sub ------------------------------------------------------------------------------- Function: MATRIX mat_inv (MATRIX A) Synopsis: find the inverse of a matrix Parameter: A: allocated square matrix Return Value: a newly allocated square matrix which is the inverse of A Example: MATRIX A, AI; /* * A must be a square matrix */ A = mat_creat( 7, 7, UNIT_MATRIX ); ... /* * find the inverse of A */ AI = mat_inv( A ); ... See Also: mat_tran, mat_add, mat_sub ------------------------------------------------------------------------------- Function: MATRIX mat_tran( MATRIX A ) Synopsis: find the transpose of a matrix Parameter: A: allocated matrix Return Value: a newly allocated matrix which is the transpose of A Example: MATRIX A, T; A = mat_creat( 3, 5, UNDEFINED ); ... T = mat_tran( A ); ... See Also: mat_inv ------------------------------------------------------------------------------- =============================================================================== 5. DETERMINANT OPERATIONS =============================================================================== ------------------------------------------------------------------------------- Function: MATRIX mat_submat (MATRIX A, int i, int j) Synopsis: form a new matrix by deleting a row and a column of A Parameter: A: allocated matrix i, j: row and column of A which will not appear in the resulting matrix Return Value: a new matrix whose dimensions are 1 less than A Example: MATRIX A, B A = mat_creat( 3, 4, UNDEFINED ); ... B = mat_submat( A, 2, 2 ); /* * suppose A = [ 1 2 3 4 ] * [ 3 3 4 5 ] * [ 6 7 9 9 ] * * then B = [ 1 2 4 ] * [ 3 3 5 ] */ Note: Do not be misled -- the contents in A will NOT be changed See Also: mat_det, mat_cofact, mat_minor ------------------------------------------------------------------------------- Function: double mat_cofact (MATRIX A, int i, int j) Synopsis: find out the cofactor of A(i,j) Parameter: A: allocated square matrix i,j: row, column position of A for the cofactor Return Value: the value of cofactor of A(i,j) Example: MATRIX A; A = mat_creat( 5, 5, UNIT_MATRIX ); ... printf( "cofactor of A(0,2) = %f\n", mat_cofact( A, 0, 2 )); See Also: mat_det, mat_minor ------------------------------------------------------------------------------- Function: double mat_minor (MATRIX A, int i, int j) Synopsis: find out the minor of A(i,j) Parameter: A: allocated square matrix i,j: row, column position of A for the minor Return Value: the value of minor of A(i,j) Example: MATRIX A; A = mat_creat( 5, 5, UNIT_MATRIX ); ... printf( "minor of A(0,2) = %f\n", mat_minor( A, 0, 2 )); See Also: mat_det, mat_cofact ------------------------------------------------------------------------------- Function: double mat_det (MATRIX A) Synopsis: find the determinant of a matrix Parameter: A: allocated square matrix Return Value: the determinant value of |A| Example: MATRIX A; double det; A = mat_creat( 5, 5, UNIT_MATRIX ); det = mat_det( A ); See Also: mat_cofact, mat_minor, mat_submat ------------------------------------------------------------------------------- =============================================================================== 6. ADVANCED MATRIX OBJECT MATHEMATICAL OPERATION =============================================================================== ------------------------------------------------------------------------------- Function: MATRIX mat_lsolve (MATRIX A, MATRIX B) Synopsis: solve simultaneous linear equation AX = B given A, B Parameter: A, B: allocated matrix Return Value: newly allocated matrix X in AX = B Example: MATRIX A, B, X; A = mat_creat( 5, 5, UNDEFINED ); fgetmat( A, stdin ); ... B = mat_creat( 5, 1, UNDEFINED ); fgetmat( B, stdin ); ... X = mat_lsolve( A, B ); mat_dump( X ); Note: number of rows in A and B must be equal See Also: mat_lsolve_durbin ------------------------------------------------------------------------------- Function: MATRIX mat_lsolve_durbin (MATRIX A, MATRIX B) Synopsis: simultaneous linear equations wtih Levinson-Durbin method Parameter: A, B: allocated matrix where A is an autocorrelated matrix and B is derived from A A, B must be the following forms: | a0 a1 a2 .. an-1 | | x1 | | a1 | | a1 a0 a1 .. an-2 | | x2 | | a2 | | a2 a1 a0 .. an-3 | | x3 | = | .. | | ... | | .. | | .. | | an-1 an-2 .. .. a0 | | xn | | an | where A is a symmetric Toeplitz matrix and B in the above format (related to A) Return Value: a newly allocated matrix X which is the solution of AX = B Example: this method only applies to certain A, B only. e.g. A = [1 3 9] B = [3] [3 1 3] [9] [9 3 1] [12] <- the last one is unrelated to A See Also: mat_SymToeplz ------------------------------------------------------------------------------- Function: MATRIX mat_SymToeplz (MATRIX R); Synopsis: create a symmetric Toeplitz matrix from a Autocorrelation vector Parameter: R: allocated matrix of dimension n x 1 Return Value: a newly allocated symmetrical Toeplitz matrix Example: e.g. MATRIX A, R; R = mat_creat( 3, 1, UNDEFINED ); ... A = mat_SymToeplz( R ); /* * if * * R = [1 3 9] A = [1 3 9] * [3 1 3] * [9 3 1] * */ See Also: mat_lsolve_durbin -------------------------------------------------------------------------------